home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Technology Seed / ADC Seed CD - July 1999.toast / USB / Mac OS USB DDK v1.2 / Examples / PrinterClassDriver / TradDriverLoaderLib.h < prev    next >
Encoding:
C/C++ Source or Header  |  1999-04-15  |  9.6 KB  |  210 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        TradDriverLoaderLib.h
  3.  
  4.     Contains:    C interface for the pseudo-DriverLoaderLib for 'DRVR's.
  5.  
  6.     Version:    xxx put version here xxx
  7.  
  8.  
  9.  
  10.     Copyright:    © 1996, 1998 by Apple Computer, Inc., all rights reserved.
  11.  
  12. */
  13.  
  14. #include <Types.h>
  15. #include <Devices.h>
  16.  
  17. #ifdef __cplusplus
  18. extern "C" {
  19. #endif
  20.  
  21. ///////////////////////////////////////////////////////////////////////////
  22.  
  23. // The following routines are implemented with semantics virtually identical
  24. //  to those found in DriverLoaderLib.  You should look in
  25. //  "Designing PCI Cards and Drivers for Power Macintosh Computers" for
  26. //  documentation.  You can FTP an electronic copy from:
  27. /*  <ftp://ftpdev.info.apple.com//Developer_Services/
  28.      Technical_Documentation/PCI_Information/Designing_PCI_Cards_-_Driv.sit.>
  29. */
  30.  
  31. extern pascal SInt16 TradHigherDriverVersion(NumVersion *dv1, NumVersion *dv2);
  32.  
  33. extern pascal UnitNumber TradHighestUnitNumber(void);
  34.  
  35. extern pascal OSErr TradDriverGestaltOn(DriverRefNum refNum);
  36.  
  37. extern pascal OSErr TradDriverGestaltOff(DriverRefNum refNum);
  38.  
  39. extern pascal Boolean TradDriverGestaltIsOn(DriverFlags flags);
  40.  
  41. extern pascal OSErr TradLookupDrivers(UnitNumber beginningUnit,
  42.                                         UnitNumber endingUnit,
  43.                                         Boolean emptyUnits,
  44.                                         ItemCount *returnedRefNums, 
  45.                                         DriverRefNum *refNums);
  46.  
  47. ///////////////////////////////////////////////////////////////////////////
  48.  
  49. // The following routines are similar to the corresponding routines in
  50. //  DriverLoaderLib, but their interface differs because of the
  51. //  inherent differences between 'DRVR's and 'ndrv's.  The comments
  52. //  cover the differences for each routine.  If there's a difference
  53. //  that's not commented, it's most probably a bug and you should let
  54. //  me know.
  55.  
  56. extern pascal OSErr TradInstallDriverFromPtr(DRVRHeaderPtr driver,
  57.                                                 UnitNumber beginningUnit,
  58.                                                 UnitNumber endingUnit,
  59.                                                 DriverRefNum *refNum);
  60.     // This routine is similar to InstallDriverFromMemory except
  61.     //  that you pass a pointer to the 'DRVR', rather than a base pointer
  62.     //  and length.  This pointer is copied verbatim into the dCtlDriver
  63.     //  field of the DCE, so you have to make sure that it's in
  64.     //  the system heap if the driver is going to hang around longer than
  65.     //  your application.
  66.     // One other deviation from InstallDriverFromMemory is that this
  67.     //  call won't replace an existing driver.  This is because 'DRVR's
  68.     //  don't have infrastructure to support this.  If there's already
  69.     //  a driver of the same name in the unit table, the call will fail
  70.     //  with a dupFNErr, and *refNum will be set to the refnum of the
  71.     //  existing driver.
  72.     // The semantics of the endingUnit match those of DriverLoaderLib,
  73.     //  ie the call will not grow the unit table unless endingUnit is
  74.     //  greater than TradHighestUnitNumber.  The simplest way to work
  75.     //  this is to pass TradHighestUnitNumber() + 1 to endingUnit.
  76.     // If the call fails, it's your responsibility to dispose of the
  77.     //  the driver pointer.  If it succeeds, the system has a copy
  78.     //  of the pointer, which can be disposed by calling TradRemoveDriver.
  79.  
  80. extern pascal OSErr TradInstallDriverFromHandle(DRVRHeaderHandle driver,
  81.                                                 UnitNumber beginningUnit,
  82.                                                 UnitNumber endingUnit,
  83.                                                 DriverRefNum *refNum);
  84.     // This routine is similar to InstallDriverFromMemory except
  85.     //  that you pass a handle to the 'DRVR', rather than a base pointer
  86.     //  and length.  This is generally more convenient in the traditional
  87.     //  'DRVR' world.
  88.     // In most other respects, this routine works like TradInstallDriverFromPtr.
  89.     //  The routine simply creates a pointer in the system heap and copies
  90.     //  your driver into it, then calls TradInstallDriverFromPtr.  Because
  91.     //  a copy is made, you do not have to ensure that the handle you
  92.     //  pass in is in the system heap.
  93.     // Regardless of whether call succeeds or fails, it's your responsibility
  94.     //  to dispose of the driver handle.
  95.     
  96. extern pascal OSErr TradInstallDriverFromResource(SInt16 rsrcID, StringPtr rsrcName,
  97.                                                 UnitNumber beginningUnit,
  98.                                                 UnitNumber endingUnit,
  99.                                                 DriverRefNum *refNum);
  100.     // This call offers functionality like InstallDriverFromFile.
  101.     //  It differs from InstallDriverFromFile in that the driver is expected
  102.     //  to be in a resource in the current resource file.  If rsrcName is nil,
  103.     //  the call uses Get1Resource('DRVR', rsrcID) to get the driver.  If
  104.     //  rsrcName is not nil, it uses Get1NamedResource('DRVR', rsrcName)
  105.     //  to get the driver.
  106.     // In most other respects, this routine works like TradInstallDriverFromPtr.
  107.     // If the call fails, the routine will clean up after itself.  If the
  108.     //  call succeeds, the driver code is left as a memory block in the system
  109.     //  heap, which can be cleaned up by calling TradRemoveDriver.
  110.  
  111. extern pascal OSErr TradGetDriverInformation(DriverRefNum refNum,
  112.                                                 UnitNumber *thisUnit,
  113.                                                 DriverFlags *flags,
  114.                                                 StringPtr name,
  115.                                                 DRVRHeaderPtr *driverHeader
  116.                                                 );
  117.     // This routine is like GetDriverInformation except that it only
  118.     //  returns information that's pertinant to the traditional 'DRVR'
  119.     //  world.  driverHeader comes back as a pointer to the beginning
  120.     //  of the 'DRVR' header.
  121.     // Note that this routine works for both drivers installed by
  122.     //  this library and other drivers, however for drivers not installed
  123.     //  by this library (ie 'RAM'-based drivers), driverHeader may be a 
  124.     //  half dereferenced handle, locked or unlocked.  You have been warned.
  125.     // Also, driverHeader can come back set to nil, if the driver
  126.     //  is installed but its code has been purged, for example a DA.
  127.     //  You must check for this before deferencing it.  If driverHeader
  128.     //  is set to nil, name will be set to the empty string.
  129.  
  130. extern pascal OSErr TradOpenInstalledDriver(DriverRefNum refNum, SInt8 ioPermission);
  131.     // This routine has the same semantics as OpenInstalledDriver
  132.     //  except that the ioPermission parameter must be fsRdWrPerm.  This is
  133.     //  because we call through to the Device Manager's OpenDriver routine,
  134.     //  and that doesn't support passing in permissions.  I could switch the
  135.     //  implementation to use PBOpen, but PBOpen is a trap fraught with much
  136.     //  danger, so I'm avoiding it at the moment.
  137.     // The danger associated with PBOpen is that it's highly overloaded,
  138.     //  being used for FSOpen, PBOpen, PBHOpen, OpenSlot, OpenDriver,
  139.     //  OpenDeskAcc, and so on.  If you get the glue wrong, you die in
  140.     //  strange and evil ways.  So I'm bypassing the entire problem by
  141.     //  ignoring ioPermission.  I may revisit this decision, but not soon.
  142.  
  143. extern pascal OSErr TradRemoveDriver(DriverRefNum refNum, Boolean immediate);
  144.     // This routine implements similar semantics to RemoveDriver, except
  145.     //  that the Immediate parameter must be false.  This is because
  146.     //  we close the driver using PBCloseSync, which is a queued
  147.     //  command, just like all the others.  We have no way to bypass
  148.     //  this.
  149.     // An important thing to note is that you should only call this on drivers
  150.     //  you installed using this library's TradInstallDriverFromHandle
  151.     //  and TradInstallDriverFromResource routine.  Don't call it on
  152.     //  drivers installed by other people and be careful when calling it on
  153.     //  drivers installed using TradInstallDriverFromPtr because you might
  154.     //  be disposing the driver code even though a) it might not actually be a
  155.     //  Memory Manager pointer block, or b) it might be still in use
  156.     //  by another driver.
  157.  
  158. extern pascal OSErr TradRenameDriver(DriverRefNum refNum, ConstStr255Param newDriverName);
  159.     // This routine is implemented with the caveat that you can't
  160.     //  make the driver name longer.  This is because the 'DRVR'
  161.     //  name is actually stored in the code resource which implements
  162.     //  the driver, and making it longer would cause it to run into
  163.     //  the code that immediately follows the name.
  164.     // The reason why I implemented this routine at all is because
  165.     //  it's useful for installing multiple copies of the same driver.
  166.     //  For example, you can install ".Q_Out", then rename it to
  167.     //  ".QAOut", and then install ".Q_Out" again, and rename that to
  168.     //  ".QBOut".  This can be very useful when testing and debugging
  169.     //  your driver (or TradDriverLoaderLib for that matter :).
  170.     // You should take extreme care when calling this routine on drivers that
  171.     //  weren't installed with this library.  Some of these drivers might
  172.     //  not like being renamed in this way.
  173.  
  174. ///////////////////////////////////////////////////////////////////////////
  175.  
  176. // The following routines from DriverLoaderLib were not implemented because
  177. //  they make no sense at all in the world of 'DRVR's.
  178.  
  179. // VerifyFragmentAsDriver
  180. // GetDriverMemoryFragment
  181. // GetDriverDiskFragment
  182. // InstallDriverFromFragment
  183. // SetDriverClosureMemory
  184. // -- If they've got fragment in the name, it's hard to map them into the
  185. // 'DRVR' world.  Traditional 'DRVR's just aren't code fragments!
  186.  
  187. // InstallDriverFromFile -- This routine assumes that there's only
  188. //    one driver in a file, which is not the case for traditional 'DRVR's
  189. //  which are normally stored as resources.  The basic functionality has
  190. //  been subsumed by TradInstallDriverFromResource.
  191.  
  192. // InstallDriverFromDisk
  193. // FindDriversForDevice
  194. // FindDriverCandidates
  195. // ScanDriverCandidates
  196. // GetDriverForDevice
  197. // InstallDriverForDevice
  198. // -- These routines all assume that there's some magic way of matching
  199. //  drivers to their name register nodes.  In the traditional world, there
  200. //  is no name registry and, even if there was, there's no way to match
  201. //  devices against hardware.  So these routines are not sensible in the
  202. //  traditional world. 
  203.  
  204. // ReplaceDriverWithFragment -- There's no good way to replace a traditional
  205. //  device driver; the infrastructure just isn't there.
  206.  
  207. #ifdef __cplusplus
  208. }
  209. #endif
  210.